Fox's Git Mirrors
docs/en/microvm.md 633735d797cc5f5d48cb2e22e8fd7cd743930daf (633735d7) Text, 3.82 KB
Firecracker microvm
Run T383838reticulum-go inside an Amazon Firecracker microVM. The default path is aimed at nested VMs (Firecracker inside another VM) where guest TAP networking is unreliable.
Requirements
• Linux with T383838/dev/kvm readable
• firecracker on T383838PATH
• Go toolchain (to build the guest rootfs and host bridge binary)
• Optional: pasta only when using T383838NET=1 rootless TAP (often broken when nested)
Quick start
T282828
make microvm-up
# or: task microvm:up
# or: ./microvm/up.sh
That will:
1. Download a Firecracker CI guest kernel into T383838microvm/out/ (first run)
2. Build a static guest rootfs with busybox + T383838reticulum-go
3. Start the microVM detached (T383838NET=0, VSOCK only)
4. Start a host bridge that pipes HDLC into the guest over Firecracker vsock
Stop everything:
T282828
make microvm-stop
# or: ./microvm/stop.sh
Add a community hub
Edit T383838microvm/host-bridge.config and uncomment or add an interface under T383838[interfaces], for example:
T282828
[[My Hub]]
type = BackboneInterface
enabled = Yes
remote = hub.example.com
target_port = 4242
max_reconnect_tries = -1
TCP hubs use TCPClientInterface with targethost / targetport. Then restart:
T282828
make microvm-stop
make microvm-up
The host process owns clearnet. The guest joins the mesh through the T383838Microvm Guest pipe (Firecracker vsock CONNECT).
Layout
┌────────────────────────────────┬──────────────────────────────────────────────┐
│ Path │ Role │
├────────────────────────────────┼──────────────────────────────────────────────┤
│ T383838microvm/up.sh │ One-shot prepare + start │
│ T383838microvm/fetch-kernel.sh │ Download T383838out/vmlinux │
│ T383838microvm/build-rootfs.sh │ Build T383838out/rootfs.ext4 │
│ T383838microvm/run.sh │ Start Firecracker │
│ T383838microvm/run-host-bridge.sh │ Host reticulum + vsock pipe │
│ T383838microvm/stop.sh │ Stop guest, pasta, and host bridge │
│ T383838microvm/guest/reticulum.config │ Guest config (VSOCK hub, persistent storage) │
│ T383838microvm/host-bridge.config │ Host config (vsock pipe + your hubs) │
│ T383838microvm/out/ │ Kernel, rootfs, sockets, logs (gitignored) │
└────────────────────────────────┴──────────────────────────────────────────────┘
Networking modes
Default: host bridge (recommended in nested VMs)
T282828
NET=0 ./microvm/up.sh
Guest listens on AF_VSOCK. Host uses PipeInterface + T383838vsock-connect.sh to speak Firecracker UDS T383838CONNECT. No guest TAP.
Guest-only
T282828
./microvm/up.sh --guest-only
# later:
./microvm/run-host-bridge.sh
Rootless TAP (T383838NET=1)
Uses pasta to create a TAP and NAT. Useful on bare metal. Nested Firecracker often fails with tap write errors. Prefer the host bridge there.
T282828
NET=1 ./microvm/up.sh --guest-only
Host TAP
If you already have a TAP (requires T383838CAP_NET_ADMIN on the host):
T282828
TAP_DEV=tap0 DETACH=1 ./microvm/run.sh
Configure guest IP via T383838microvm/guest/microvm-net before T383838build-rootfs.sh.
Persistence
Guest storage lives on the rootfs under T383838/etc/reticulum/storage (next to the guest config). Rebuilds of T383838rootfs.ext4 replace that disk image. Keep identities you care about outside the image or avoid T383838--rebuild when you need them.
Makefile and Task
┌──────────────────────┬──────────────────────┬────────────────────────────────────────────────────┐
│ Make │ Task │ Action │
├──────────────────────┼──────────────────────┼────────────────────────────────────────────────────┤
│ T383838make microvm-up │ T383838task microvm:up │ Fetch kernel if needed, build rootfs if needed, s… │
│ T383838make microvm-stop │ T383838task microvm:stop │ Stop guest and host bridge │
│ T383838make microvm-kernel │ T383838task microvm:kernel │ Fetch kernel only │
│ T383838make microvm-rootfs │ T383838task microvm:rootfs │ Build rootfs only │
│ T383838make microvm-rebuild │ T383838task microvm:rebuild │ Force kernel+rootfs rebuild then up │
└──────────────────────┴──────────────────────┴────────────────────────────────────────────────────┘
Logs
• Guest serial: T383838microvm/out/firecracker.stdout
• Firecracker log: T383838microvm/out/firecracker.log
• Host bridge: T383838microvm/out/host-bridge.log
Related documents
• Interfaces for VSOCK, Pipe, TCP, and Backbone keys
• Configuration for config file format
• Architecture for deployment models
Served by rngit 1.5.2 - Generated in 0.02s